Pré-autorizações · Referência

Consultar pré-autorizações

Lê o status atual de uma operação pelo id, ou encontra as operações de um externalReference.

Os webhooks avisam cada mudança. A consulta existe para reconciliar: depois de o seu endpoint ficar fora do ar, antes de agir sobre uma operação antiga ou quando o seu ERP perdeu o id. Não é preciso consultar em ciclo — o limite de requisições vale também aqui.

Por id

GET /api/integration/v1/pre-authorizations/{id} escopo preauth:read

Parâmetro	Onde	Descrição
`id`	path	O `id` devolvido na criação, ou o `anticipationId` de um evento.

200 com a operação no mesmo formato da criação, com o status de agora.

Você enxerga as operações em que a sua empresa ou uma filial dela é a tomadora — as criadas pela API, pela plataforma ou por qualquer outro canal. Operação de outra empresa responde 404, mesmo que exista.

Requisição

curl https://app.oneos.com.br/api/integration/v1/pre-authorizations/48213 \
  -H "Authorization: Bearer $ONEOS_API_KEY"

const response = await fetch('https://app.oneos.com.br/api/integration/v1/pre-authorizations/48213', {
  headers: { Authorization: `Bearer ${process.env.ONEOS_API_KEY}` },
})

const preAuthorization = await response.json()
console.log(preAuthorization.status) // 'TO_APPROVE'

response = requests.get(
    "https://app.oneos.com.br/api/integration/v1/pre-authorizations/48213",
    headers={"Authorization": f"Bearer {os.environ['ONEOS_API_KEY']}"},
    timeout=30,
)

print(response.json()["status"])  # TO_APPROVE

<?php
$ch = curl_init('https://app.oneos.com.br/api/integration/v1/pre-authorizations/48213');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ONEOS_API_KEY')],
]);
$body = json_decode(curl_exec($ch), true);
echo $body['status']; // TO_APPROVE

200

{
  "id": 48213,
  "status": "TO_APPROVE",
  "externalReference": "PED-4581",
  "payer": {
    "cnpj": "44555666000199",
    "name": "Construtora Exemplo LTDA"
  },
  "supplier": {
    "cnpj": "11222333000181",
    "name": "Fornecedor Exemplo ME"
  },
  "invoice": {
    "amount": 18400,
    "dueDate": "2026-11-30",
    "number": "48211",
    "withheldTaxAmount": 0
  },
  "expiresAt": "2026-09-19T02:59:59.000Z",
  "createdAt": "2026-09-15T13:00:00.000Z"
}

Lista

GET /api/integration/v1/pre-authorizations escopo preauth:read

Query	Descrição
`externalReference`	Igualdade exata com o valor enviado na criação (até 100 caracteres). Espaços nas pontas são ignorados.
`status`	Um ou mais status. Repita o parâmetro: `?status=IN_PRE_AUTH&status=TO_APPROVE`.
`page`	Página, a partir de 1. Padrão 1.
`limit`	Itens por página, até 100. Padrão 20.

200 com data (operações no formato da criação) e pagination (page, limit, total, totalPages). A ordem é da mais recente para a mais antiga. Sem filtros, a lista traz todas as operações da sua empresa.

Requisição

curl -G https://app.oneos.com.br/api/integration/v1/pre-authorizations \
  -H "Authorization: Bearer $ONEOS_API_KEY" \
  --data-urlencode "externalReference=PED-4581"

const query = new URLSearchParams({ externalReference: 'PED-4581' })
const response = await fetch(`https://app.oneos.com.br/api/integration/v1/pre-authorizations?${query}`, {
  headers: { Authorization: `Bearer ${process.env.ONEOS_API_KEY}` },
})

const { data, pagination } = await response.json()

response = requests.get(
    "https://app.oneos.com.br/api/integration/v1/pre-authorizations",
    headers={"Authorization": f"Bearer {os.environ['ONEOS_API_KEY']}"},
    params={"externalReference": "PED-4581"},
    timeout=30,
)

page = response.json()
operations, pagination = page["data"], page["pagination"]

<?php
$query = http_build_query(['externalReference' => 'PED-4581']);
$ch = curl_init('https://app.oneos.com.br/api/integration/v1/pre-authorizations?' . $query);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ONEOS_API_KEY')],
]);
$page = json_decode(curl_exec($ch), true);

200

{
  "data": [
    {
      "id": 48213,
      "status": "TO_APPROVE",
      "externalReference": "PED-4581",
      "payer": {
        "cnpj": "44555666000199",
        "name": "Construtora Exemplo LTDA"
      },
      "supplier": {
        "cnpj": "11222333000181",
        "name": "Fornecedor Exemplo ME"
      },
      "invoice": {
        "amount": 18400,
        "dueDate": "2026-11-30",
        "number": "48211",
        "withheldTaxAmount": 0
      },
      "expiresAt": "2026-09-19T02:59:59.000Z",
      "createdAt": "2026-09-15T13:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

Erros

Além dos erros de autenticação e do limite de requisições:

Status	Código	Quando acontece
400	`BAD_REQUEST`	O `id` não é um número.
400	`VALIDATION_ERROR`	Query fora do formato: `status` desconhecido ou `limit` acima do teto.
403	`INTEGRATION_SCOPE_FORBIDDEN`	A chave não tem o escopo `preauth:read`. Crie uma chave com o escopo. A rotação mantém os escopos da chave antiga.
404	`ANTICIPATION_NOT_FOUND`	Não existe operação com esse `id` em que a sua empresa seja a tomadora.