WS313 - Document events

WS313 - Our service for document downloads

This integration aims to open a request to download documents.

Authentication

Calls will have transport-level authentication (Basic Authentication);
Request user / password from the account administrator.

Features

URL

<https://entregas-api.comprovei.com/v1/events/send>
Method:

POST

This integration returns a protocol for monitoring - WS301

Request Example

{
    "<chave_documento>" : {
        "route_number" : "String",
        "route_date" : "String",
        "driver" : "String",
        "code" : "String",
        "start_date" : "String",
        "end_date" : "String",
        "pictures" : [{
            "link" : "String",
            "subtitle" : "String"
        }],
        "annotation" : "Sting",
        "signature" : {
            "link" : "String",
            "subtitle" : "String"
        },
        "coordinates" : {
            "latitude" : 0,
            "longitude" : 0
        },
        "device_model" : "String",
        "device_id" : "String"
    }
}

Our JSON

Parameters

Property	Type	Description
Access key	JSON	Document access key to download

JSON Access Key

Parameter	Type	Required	Description
`route_number`	string	No	Code given to the route in Comprovai.
`route_date`	string	No	Route date in Comprovei ('YYYY-MM-DD').
`driver`	string	No	Driver assigned to the route in Comprovai.
`code`	string	Yes	Occurrence code for discharge. You must be registered with Comprovai.
`start_date`	string	Yes	Date and time the occurrence began ('YYYY-MM-DD HH:mm:ss').
`end_date`	string	Yes	Date and time when the occurrence ended ('YYYY-MM-DD HH:mm:ss').
`pictures`	object array	No	Set Attachment containing photos of the delivery*.
`annotation`	string	No	Note regarding delivery*.
`signature`	object	No	Customer's digital signature* in the format of attachment.
`coordinates`	object	Yes	Coordinates of the delivery.
`device_model`	string	No	Model of the device used by the driver during the route.
`device_id`	string	No	Device ID used by the driver during the route.

Warning

*They will be validated according to the chosen occurrence code. For example: if the incident requires a photo, the pictures parameter becomes mandatory.

Annex

Parameter	Type	Required	Description
`link`	string	*	Url of the image to be attached to the document**.
`subtitle`	string	*	Additional information regarding the image.

Warning

All images must be in jpeg or png format.
The access link must allow downloading.
The link must have http protocol.
If you need to grant access only to a fixed IP, contact support@comprovei.com
**If the download attachment file is not yet available, the link must return HTTP status 404.

Coordinates

Parameter	Type	Required	Description
`latitude`	number	Yes	Latitude of the event location in fractional format using American notation.
`longitude`	number	Yes	Longitude of the event location in fractional format using American notation.

Warning

All optional fields will be validated if sent, that is, they cannot be blank, if you do not wish to send the information, do not add the fields.

Success:

Code: 202
Content:

{
    "message" : "OK",
    "protocol" : "<protocol>"
}

{
    "message" : "Algumas rotas enviadas apresentaram erros. Consulte o protocolo para detalhes",
    "protocol" : "<protocol>" 

}

Error:

Code: 400
Content:

{
    "message": "Corpo da requisição está vazio"
}

{
    "message" : "Corpo da requisição não é um JSON válido" 
}

{
    "message" : "O limite de baixas por requisição é 10" 
}

{ 
    "message" : "Em <chave_documento>, a chave do documento não deve estar vazia" 
}

{
    "message" : "Em <chave_documento>, o corpo do documento deve ser um objeto JSON" 
}

{
    "message" : "Em <chave_documento>, campo 'route_number' deve ser alfanumérico" 
}

{
    "message" : "Em <chave_documento>, campo 'route_date' deve ser alfanumérico" 
}

{
    "message" : "Em <chave_documento>, '<date>' não é uma data válida para 'route_date'" 
}

{
    "message" : "Em <chave_documento>, campo 'driver' deve ser alfanumérico" 
}

{
    "message" : "Em <chave_documento>, campo 'driver' não deve estar vazio" 
}

{
    "message" : "Em <chave_documento>, se o campo 'route_number' for enviado, os campos 'route_date' e 'driver' são obrigatórios" 
}

{
    "message" : "Em <chave_documento>, se o campo 'route_date' for enviado, os campos 'route_number' e 'driver' são obrigatórios" 
}

{
    "message" : "Em <chave_documento>, se o campo 'driver' for enviado, os campos 'route_number' e 'route_date' são obrigatórios" 
}

{
    "message" : "Em <chave_documento>, campo 'code' é obrigatório" 
}

{
    "message" : "Em <chave_documento>, campo 'code' deve ser alfanumérico" 
}

{
    "message" : "Em <chave_documento>, campo 'code' não deve estar vazio" 
}

{
    "message" : "Em <chave_documento>, campo 'start_date' é obrigatório" 
}

{
    "message" : "Em <chave_documento>, campo 'start_date' deve ser alfanumérico" 
}

{
    "message" : "Em <chave_documento>, '<date>' não é uma data válida para 'start_date'" 
}

{
    "message" : "Em <chave_documento>, campo 'end_date' é obrigatório" 
}

{
    "message" : "Em <chave_documento>, campo 'end_date' deve ser alfanumérico" 
}

{
    "message" : "Em <chave_documento>, '<date>' não é uma data válida para 'end_date'" 
}

{
    "message" : "Em <chave_documento>, campo 'pictures' deve ser um array" 
}

{
    "message" : "Em <chave_documento>, campo 'pictures' deve conter pelo menos uma posição" 
}

{
    "message" : "Em <chave_documento> > 'pictures': posição <posicao> deve ser um objeto JSON" 
}

{
    "message" : "Em <chave_documento> > 'pictures', posição <posicao>: campo 'link' é obrigatório" 
}

{
    "message" : "Em <chave_documento> > 'pictures', posição <posicao>: campo 'link' deve ser alfanumérico" 
}

{
    "message" : "Em <chave_documento> > 'pictures', posição <posicao>: a url enviada não é válida" 
}

{
    "message" : "Em <chave_documento> > 'pictures', posição <posicao>: campo 'subtitle' deve ser alfanumérico" 
}

{
    "message" : "Em <chave_documento> > 'pictures', posição <posicao>: campo 'subtitle' não deve estar vazio" 
}

{
    "message" : "Em <chave_documento>, Campo 'annotation' deve ser alfanumérico" 
}

{
    "message" : "Em <chave_documento>, Campo 'annotation' não deve estar vazio" 
}

{
    "message" : "Em <chave_documento>, Campos 'signature' deve ser um objeto JSON" 
}

{
    "message" : "Em <chave_documento> > 'signature': campo 'link' é obrigatório" 
}

{
    "message" : "Em <chave_documento> > 'signature': campo 'link' deve ser alfanumérico" 
}

{
    "message" : "Em <chave_documento> > 'signature': a url enviada não é válida" 
}

{
    "message" : "Em <chave_documento> > 'signature': campo 'subtitle' deve ser alfanumérico" 
}

{
    "message" : "Em <chave_documento> > 'signature': campo 'subtitle' não deve estar vazio" 
}

{
    "message" : "Em <chave_documento>, campo 'coordinates' é obrigatório" 
}

{
    "message" : "Em <chave_documento>, campo 'coordinates' deve ser um objeto JSON" 
}

{
    "message" : "Em <chave_documento> > 'coordinates': Campos 'latitude' e 'longitude' são obrigatórios" 
}

{
    "message" : "Em <chave_documento> > 'coordinates': 'latitude' deve ser do tipo númerico" 
}

{
    "message" : "Em <chave_documento> > 'coordinates': 'longitude' deve ser do tipo númerico" 
}

{
    "message" : "Em <chave_documento>, campo 'device_model' deve ser alfanumérico" 
}

{
    "message" : "Em <chave_documento>, campo 'device_id' deve ser alfanumérico" 
}

{
    "errors": [
        {
            "occurrence_code": "<codigo_ocorrencia>",
            "dkey": "<chave_documento>",
            "errors": [
                { "code" : 404, "message" : "Documento não encontrado" },
                { "code" : 404, "message" : "Ocorrência não encontrada" },
                { "code" : 400, "message" : "Mais de uma rota encontrada" },
                { "code" : 400, "message" : "Rota já está finalizada ou não foi encontrada" },
                { "code" : 400, "message" : "Documento não está associado à uma rota" },
                { "code" : 400, "message" : "Documento já está finalizado" },
                { "code" : 400, "message" : "A ocorrência escolhida precisa de pelo menos uma foto" },
                { "code" : 400, "message" : "A ocorrência escolhida precisa da assinatura" },
                { "code" : 400, "message" : "A ocorrência escolhida precisa de uma anotação" },
                { "code" : 400, "message" : "A ocorrência escolhida não pode ser aplicada a paradas de transbordo" },
                { "code" : 400, "message" : "A ocorrência escolhida não pode ser aplicada a paradas de entrega" },
                { "code" : 400, "message" : "A ocorrência escolhida não pode ser aplicada a paradas de coletas" }
            ]
        }
    ],
    "message": "Foram encontrados erros em todos os documentos enviados"
}