Consultar Estado

Consultar Estado

GET /v1/client/status/{requestId}

Usa o requestId devolvido na submissão.

Podes usar o parâmetro de query opcional return_fields para filtrar os campos retornados na resposta (separados por vírgula). Os valores aceites são:

  • requestId: ID interno da requisição
  • status: Estado atual do processamento
  • agtRequestId: ID da requisição na AGT
  • message: Mensagem descritiva do estado ou erro
  • agt_response: O JSON bruto enviado pela AGT (apenas disponível após a AGT responder)

Exemplo de uso: ?return_fields=agtRequestId,status,agt_response

curl https://<host>/v1/client/status/<requestId> \
  -H "X-API-Key: agt_live_XXXXXXXX.xxxxxxxxxxxxxxxxxxxxxx"
{
  "requestId": "uuid",
  "status": "VALID",
  "agtRequestId": "202500000000118",
  "message": "string|null"
}

Valores de status

Em progresso (continua a consultar):

RECEIVED → SENT_TO_AGT → PROCESSING

Final (pára de consultar):

ValorSignificado
VALIDDocumento aceite pela AGT
VALID_PENALTYAceite, mas fora do prazo (com penalidade)
PROCESSED_SUCCESSProcessamento concluído, sem faturas inválidas
PROCESSED_PARTIALProcessamento concluído, com faturas válidas e inválidas
PROCESSED_ALL_INVALIDProcessamento concluído, sem faturas válidas
SUCCESS / COMPLETEDOperação concluída (outras consultas)
REJECTEDRejeitado pela AGT
FAILED / ERRORFalha no processamento / Cancelado
⚠️

Trata status como texto livre, não como uma lista fechada — considera qualquer valor fora de RECEIVED/SENT_TO_AGT/PROCESSING como final.

Códigos de Resultado da AGT (resultCode)

Caso solicites o campo agt_response via ?return_fields=agt_response, poderás ver o resultCode original devolvido pela AGT no processamento de faturas (especialmente em lote). O significado de cada código é:

  • 0 - Processamento concluído, sem facturas inválidas;
  • 1 - Processamento concluído, com facturas válidas e facturas inválidas;
  • 2 - Processamento concluído, sem facturas válidas;
  • 7 - Solicitação não respondida por ser prematura ou repetitiva, devendo aguardar período mínimo para repetir este pedido;
  • 8 - Processamento ainda em curso;
  • 9 - Processamento cancelado.

Erros

  • 404 — requestId não encontrado.

Estratégia recomendada

  1. Após submeter, guarda o requestId.
  2. Consulta com backoff (ex.: cada 5–10s no primeiro minuto).
  3. Configura um webhook para seres notificado automaticamente em vez de fazer polling.
Submeter DocumentosConfirmar/Rejeitar