Faturamento
O faturamento tem duas partes independentes: registrar os dados da nota (número, data, valor) e anexar o arquivo. Você pode fazer só a primeira, mas o cliente só consegue baixar a nota no app se a segunda também for feita.
O upload aceita somente PDF. Qualquer arquivo com Content-Type diferente de
application/pdf — inclusive o XML da NF-e — é recusado com 400 e a mensagem
Apenas arquivos PDF são permitidos. Se o seu ERP guarda só o XML, gere o DANFE em
PDF antes de anexar.
Registrar a nota
PUT /v1/Orders/invoiced/{orderNumber}
curl -X PUT $GROCERS_API/v1/Orders/invoiced/104821 \
-H "Authorization: Basic $BASIC" \
-H "x-contractAccountId: $TENANT" \
-H "Content-Type: application/json" \
-d '{
"number": "000012345",
"issuanceDate": "2026-07-29T15:04:22Z",
"value": 18745
}'| Campo | Formato | Observação |
|---|---|---|
number | string | número da nota fiscal |
issuanceDate | ISO 8601 UTC, com Z | data e hora de emissão |
value | inteiro | valor em centavos |
value é inteiro em centavos: R$ 187,45 se envia como 18745. Mandar 187.45 é
truncado para 187 e a nota fica registrada com um centésimo do valor.
{
"transactionId": "9c2f4b18-3a77-4e51-9d0c-5b6a1e8f2c34"
}| Código | Significado | O que fazer |
|---|---|---|
200 | aceito e enfileirado | guarde o transactionId para rastrear o processamento |
400 | validação do corpo falhou — number vazio, value ausente | corrija o corpo; retentar não resolve |
500 | falha no processamento — inclui pedido inexistente | limite a retentativa; a API não distingue os dois casos |
Anexar o arquivo
POST /v1/Storages/invoice/upload?orderId={orderId}
curl -X POST \
"$GROCERS_API/v1/Storages/invoice/upload?orderId=$ORDER_ID" \
-H "Authorization: Basic $BASIC" \
-H "x-contractAccountId: $TENANT" \
-F "files=@nfe-000012345.pdf"Repare que o upload usa orderId (o GUID interno), enquanto o registro da nota usa
orderNumber (o número visível ao cliente). Os dois vêm no payload do webhook: id e
number.
Ordem obrigatória
Esta é a aplicação da sequência canônica de Ciclo de vida do pedido ao faturamento.
Informe a separação
PATCH /v1/Orders/{orderNumber}/status com ORDER_BEING_PREPARED, ao iniciar a
separação.
Envie a alteração, se houve
PUT /v1/Orders/{orderNumber} com o finalOrderPrice e os itens conferidos. Veja
Alterar itens do pedido.
Emita a nota no seu ERP
Pelo valor final — o mesmo finalOrderPrice do passo anterior. Nada acontece na
plataforma até aqui.
Registre os dados
PUT /v1/Orders/invoiced/{orderNumber}.
Anexe o arquivo
POST /v1/Storages/invoice/upload.
Confirme o status
GET /v1/Orders/{orderNumber}/status deve responder 350. Se ainda não responder, envie
PATCH /v1/Orders/{orderNumber}/status com ORDER_INVOICED.
Consultar a nota anexada
curl "$GROCERS_API/v1/Storages/invoice?orderId=$ORDER_ID" \
-H "Authorization: Basic $BASIC" -H "x-contractAccountId: $TENANT"Serve para confirmar que o arquivo chegou antes de responder a um cliente que reclama não conseguir baixar a nota.