Skip to content

Latest commit

 

History

History
290 lines (233 loc) · 11 KB

README.es.md

File metadata and controls

290 lines (233 loc) · 11 KB
Raw

Onfleet PHP Wrapper

License Latest version Top language Downloads

Consulta este documento en otro idioma: English

Los invitamos a visitar nuestra publicación sobre el proyecto de librerías para la API para conocer más sobre nuestras iniciativas. En caso de preguntas, pueden contactarnos a través de un issue aquí o escribirnos a support@onfleet.com.

Tabla de contenidos

Sinopsis

La librería en PHP de Onfleet nos permite un acceso fácil y cómodo a la API de Onfleet.

Instalación

composer require onfleet/php-onfleet

Requerimientos

La librería de Onfleet para PHP require tener la extensión bcmath instalada.

Uso

Antes de usar la librería, es indispensable obtener una llave para la API a través de alguno de los administradores de la organización a la que pertenecemos.

La creación e integración de llaves se realiza a través del panel principal de Onfleet.

Para utilizar la librería sólo tenemos que crear una instancia de Onfleet usando la llave:

$onfleet = new Onfleet("<su_api_akey>");

Opcionalmente, se puede personalizar el timeout para hacerlo menor que el valor por defecto de la API de Onfleet (70,000 ms) suministrando un 2do parámetro:

$onfleet = new Onfleet("<su_api_akey>", 30000);

Autenticación

Una vez tenemos la instancia de Onfleet podemos probar el endpoint de autenticación:

$onfleet->verifyKey();  // Returns a boolean

Pruebas unitarias

composer run-script test

Límites

La API impone un límite de 20 peticiones por segundo entre todas las peticiones de todas las llaves de la organización. Más detalles aquí.

La librería también implementa un limitador para prevenir excesos accidentales de los límites y, eventualmente, posibles sanciones.

Operaciones CRUD soportadas

Estas son las operaciones disponibles para cada endpoint:

Entity GET POST PUT DELETE
Admins/Administrators get() create(obj), matchMetadata(obj) update(id, obj) deleteOne(id)
Containers get(id, 'workers'), get(id, 'teams'), get(id, 'organizations') x update(id, obj) x
Destinations get(id) create(obj), matchMetadata(obj) x x
Hubs get() create(obj) update(id, obj) x
Organization get(), get(id) x insertTask(id, obj) x
Recipients get(id), get(name, 'name'), get(phone, 'phone') create(obj), matchMetadata(obj) update(id, obj) x
Tasks get(query), get(id), get(shortId, 'shortId') create(obj), clone(id), forceComplete(id), batch(obj), autoAssign(obj), matchMetadata(obj) update(id, obj) deleteOne(id)
Teams get(), get(id), getWorkerEta(id, obj), getTasks(id) create(obj), autoDispatch(id, obj) update(id, obj), insertTask(id, obj) deleteOne(id)
Webhooks get() create(obj) x deleteOne(id)
Workers get(), get(query), get(id), getByLocation(obj), getSchedule(id), getTasks(id) create(obj), setSchedule(id, obj), matchMetadata(obj), getDeliveryManifest(obj) update(id, obj), insertTask(id, obj) deleteOne(id)
Custom Fields get(query) create(obj) update(obj) delete(obj)

Peticiones GET

Para obtener todos los elementos disponibles en un recurso, éstas llamadas retornan un Promise con el arreglo de los resultados:

get();
Ejemplos de get()
$onfleet->workers->get();
$onfleet->workers->get($parametros);

Opcionalmente, podemos utilizar un objeto JSON con parámetros de búsqueda en los recursos que lo soportan. En la documentación de la API se describe qué recursos lo permiten.

$onfleet->workers->get([ "phones" => "<phone_number>" ]);

$onfleet->tasks->get([ "from" => "<from_time>", "to" => "<to_time>" ]);

Para obtener uno de los elementos de un endpoint, si el parámetreo opcional paramName no es suministrado, la libraría buscará por ID. Si paramName es suministrado, se utilizará paramName:

get(<parameter>, <paramName> (optional), <queryParam> (optional));

Posibles valores de paramName:

  • id
  • name
  • phone
  • shortId
Ejemplos de get(param)
$onfleet->workers->get("<24_digit_ID>");
$onfleet->workers->get("<24_digit_ID>", [ "analytics" => true ]);

$onfleet->tasks->get("<shortId>", "shortId");

$onfleet->recipients->get("<phone_number>", "phone");
$onfleet->recipients->get("<recipient_name>", "name");
$onfleet->recipients->get("<recipient_name>", "name", [ "skipPhoneNumberValidation" => true ]);


$onfleet->containers->get("<24_digit_ID>", "workers");
$onfleet->containers->get("<24_digit_ID>", "teams");
$onfleet->containers->get("<24_digit_ID>", "organizations");

Para obtener un driver según su ubicación, podemos utilizar la función getByLocation:

getByLocation($parametros);
Ejemplos de getByLocation
$parametrosLocacion = [
  "longitude" => -122.404,
  "latitude" => 37.789,
  "radius" => 10000,
];

$onfleet->workers->getByLocation($parametrosLocacion);

Peticiones POST

Para crear un elemento de un recurso:

create($datos);
Ejemplos de create()
$datos = [
  "name" => "John Driver",
  "phone" => "+16173428853",
  "teams" => ["<team_ID>", "<team_ID> (optional)", ...],
  "vehicle" => [
    "type" => "CAR",
    "description" => "Tesla Model 3",
    "licensePlate" => "FKNS9A",
    "color" => "purple",
  ],
];

$onfleet->workers->create($datos);
Ejemplos de getDeliveryManifest()
$data = [
  "hubId" => "<hubId>", // Required
  "workerId" => "<workerId>", // Required
  "googleApiKey" => "<googleApiKey>", // Optional
  "startDate" => "<startDate>", // Optional - Timestamp format e.g. 1557936000000
  "endDate" => "<endDate>" // Optional - Timestamp format e.g. 1557936000000
];

$onfleet->workers->getDeliveryManifest($data);

Otras peticiones POST incluyen clone, forceComplete, batchCreate, autoAssign en el recurso Tasks; setSchedule en el recurso Workers; autoDispatch en el recurso Teams; y matchMetadata en todos los recursos que lo soportan. Por ejemplo:

$onfleet->tasks->clone('<24_digit_ID>');
$onfleet->tasks->forceComplete('<24_digit_ID>', $datos);
$onfleet->tasks->batchCreate($datos);
$onfleet->tasks->autoAssign($datos);

$onfleet->workers->setSchedule('<24_digit_ID>', $datos);
$onfleet->workers->getDeliveryManifest($data);

$onfleet->teams->autoDispatch('<24_digit_ID>', $datos);

$onfleet-><entity_name_pluralized>->matchMetadata($datos);

Para más información, podemos consultar la documentación sobre clone, forceComplete, batchCreate, autoAssign, setSchedule. matchMetadata, getDeliveryManifest y autoDispatch.

Peticiones PUT

Para modificar un elemento de un recurso:

update("<24_digit_ID>", $datos);
Ejemplos de update()
$nuevosDatos = [
  "name" => "Jack Driver",
];

$onfleet->workers->update("<24_digit_ID>", $nuevosDatos);
Ejemplos de insertTask()
$onfleet->workers->insertTask("<24_digit_ID>", $datos);

Peticiones DELETE

Para eliminar un elemento de un recurso:

deleteOne("<24_digit_ID>");
Ejemplos de deleteOne()
$onfleet->workers->deleteOne("<24_digit_ID>");

Ejemplos de cómo utilizar las operaciones CRUD

  • Obetener todos los recipients: 
    try {
  $tasks = $onfleet->tasks->get([ "from" =>"1557936000000", "to" => "1558022400000" });
  foreach ($tasks['tasks'] as $task) {
    if (is_set($task['recipients'][0])) {
      // Do something with the recipients
    }
  }
} catch (Exception $error) {
  // Do something with the error
}

Qué NO hacer

  • Patrón ineficiente, debemos usar metadata: 
    try {
  $workers = $onfleet->workers.get();
  for ($workers as $worker) {
    foreach ($worker['metadata'] as $metadataEntry) {
      if ($metadataEntry['name'] === "hasFreezer" && $metadataEntry['value']) {
        // Do something
      }
    }
  }
} catch (Exception $error) {
  // Do something with the error
}

// DO
try {
  $workers = $onfleet->workers->matchMetadata([["name" => "hasFreezer", "type" => "boolean", "value" => true]]);
  for ($workers as $worker) {
    // Do something
  }
} catch (Exception $error) {
  // Do something with the error
}

Ir al inicio.