v1.0.0OpenAPI 3.1.0

UNO API

Converta o PDF de duas páginas (etiqueta logística + DANFE) em uma etiqueta 100×150 mm pronta para a térmica. A API é assíncrona, usa JSON UTF-8 e autenticação Bearer, com idempotência e webhooks assinados. Toda resposta traz requestId.

Servidor

https://api-nextpy-uno.1nwz76.easypanel.host

Autenticação

Authorization: Bearer uno_live_…

Autenticação

As chaves de API ficam disponíveis com o adicional + API, contratado sobre qualquer plano pago. A chave aparece uma única vez na criação — guarde-a no cofre de segredos do ERP e envie no cabeçalho Authorization. Sem o adicional ou sem um plano pago vigente, as chamadas respondem 403.

Nunca exponha a chave em código de navegador. Os exemplos com Bearer rodam no servidor do ERP; um navegador deve passar por um proxy autenticado no seu próprio backend.

POST/api/v1/conversions

Criar uma conversão

Envie um PDF multipart com uma etiqueta logística e uma DANFE. O servidor reserva a cota e responde 202 sem esperar o processamento terminar.

Corpo · multipart/form-data

filebinaryobrigatório

PDF de duas páginas (etiqueta + DANFE).

sizestringobrigatório

100x150, 100x100, a6 ou custom.

widthMmnumberopcional

Largura 50–210, quando size=custom.

heightMmnumberopcional

Altura 50–300, quando size=custom.

Idempotency-Keyheaderobrigatório

Repetir a mesma chave retorna o mesmo resultado.

POST/api/v1/conversions

curl --fail-with-body "$UNO_API_URL/api/v1/conversions" \
  -H "Authorization: Bearer $UNO_API_KEY" \
  -H "Idempotency-Key: pedido-001-v1" \
  -F "file=@etiqueta.pdf;type=application/pdf" \
  -F "size=100x150"

Resposta

{
  "requestId": "req_…",
  "id": "cnv_…",
  "status": "queued",
  "progress": 0,
  "createdAt": "2026-01-01T00:00:00Z"
}

GET/api/v1/conversions/{id}

Consultar uma conversão

Uma etiqueta digital fica pronta em cerca de um segundo após o 202. Comece o polling 500 ms depois e repita a cada 500 ms–1 s até completed ou failed — ou receba o webhook.

queued

Aceita, aguardando o worker.

processing

A engine está executando.

completed

Inclui downloadUrl e expiresAt.

failed

Inclui código e mensagem.

GET/api/v1/conversions/{id}

curl "$UNO_API_URL/api/v1/conversions/cnv_123" \
  -H "Authorization: Bearer $UNO_API_KEY"

Resposta

{
  "id": "cnv_…",
  "status": "completed",
  "downloadUrl": "https://…",
  "expiresAt": "2026-01-01T01:00:00Z"
}

POST/api/v1/batches

Criar um lote

Envie o campo files repetido. O lote reserva a cota inteira ou rejeita a operação; o ZIP final inclui só as etiquetas aprovadas, com os contadores e erros dos demais itens.

POST/api/v1/batches

curl --fail-with-body "$UNO_API_URL/api/v1/batches" \
  -H "Authorization: Bearer $UNO_API_KEY" \
  -H "Idempotency-Key: lote-001-v1" \
  -F "files=@a.pdf;type=application/pdf" \
  -F "files=@b.pdf;type=application/pdf" \
  -F "size=100x150"

Resposta

{
  "id": "bat_…",
  "status": "queued",
  "itemCount": 2
}

GET/api/v1/batches/{id}

Consultar um lote

Consulte o estado até a composição do ZIP terminar. O download é uma URL assinada com expiração.

GET/api/v1/batches/{id}

curl "$UNO_API_URL/api/v1/batches/bat_123" \
  -H "Authorization: Bearer $UNO_API_KEY"

Resposta

{
  "id": "bat_…",
  "status": "completed",
  "completedCount": 2,
  "failedCount": 0,
  "downloadUrl": "https://…"
}

GET/api/v1/usage

Consultar o uso

O consumo da cota no período vigente: limit, reserved, confirmed e remaining.

GET/api/v1/usage

curl "$UNO_API_URL/api/v1/usage" \
  -H "Authorization: Bearer $UNO_API_KEY"

Resposta

{
  "periodStart": "2026-01-01T00:00:00Z",
  "periodEnd": "2026-02-01T00:00:00Z",
  "limit": 2000,
  "reserved": 3,
  "confirmed": 180,
  "remaining": 1817
}

Webhooks

A UNO envia conversion.completed, conversion.failed e batch.completed. Calcule HMAC-SHA-256 sobre <timestamp>.<corpo exato> e compare com X-Label-Signature.

Valide a assinatura antes de interpretar o JSON.
Rejeite timestamps antigos conforme a sua tolerância.
Deduplicate pelo X-Label-Delivery.
Responda 2xx só depois de persistir o evento.

Reentregas após 1 min, 5 min, 30 min, 2 h e 12 h.

Cabeçalhos

X-Label-Timestamp: 1790812800
X-Label-Delivery: dlv_…
X-Label-Signature: v1=<hex-hmac-sha256>

Erros

Toda falha traz um código estável e uma mensagem segura, dentro do envelope com requestId.

Código	HTTP	Significado
`invalid_request`	400	Campos ausentes ou inválidos.
`plan_required`	403	Sem plano pago vigente ou sem o adicional + API.
`file_too_large`	413	O arquivo excede o limite do plano.
`pdf_encrypted`	422	O PDF exige senha.
`unsupported_template`	422	O template não é reconhecido.
`ambiguous_template`	422	A detecção não encontrou correspondência segura.
`quota_exceeded`	403	Cota mensal atingida.
`rate_limited`	429	Limite de requisições atingido.

Limites

Com o adicional + API, o limite por minuto segue o plano: Starter 30, Pro 60 e Business 120 requisições. Um 429 inclui Retry-After. Tamanho de arquivo, lote e retenção seguem o plano ativo.