Pré-autorizações · Referência

Criar pré-autorização

Oferece ao fornecedor a antecipação de uma nota que a sua empresa vai pagar.

POST /api/integration/v1/pre-authorizations escopo preauth:write

Requisição

A sua empresa (a matriz dona da chave) é a tomadora. O fornecedor é avisado pela plataforma — ou convidado, se ainda não tiver conta. A operação nasce com status IN_PRE_AUTH.

Headers

Header		Descrição
`Authorization`	obrigatório	`Bearer oneos_sk_…`
`Content-Type`	obrigatório	`application/json`, ou `multipart/form-data` para enviar o arquivo da nota.
`Idempotency-Key`	recomendado	Torna a retentativa segura. Veja Idempotência.

Corpo

supplier object obrigatório

Fornecedor que vai receber a oferta de antecipação.
cnpj supplier. string obrigatório

CNPJ do fornecedor, com ou sem máscara. Dígitos verificadores são conferidos; CNPJ alfanumérico é aceito.
email supplier. string obrigatório

E-mail de contato do fornecedor para esta operação.

e-mailaté 255 caracteres
name supplier. string opcional

Razão social. Obrigatório quando o CNPJ ainda não está na Oneos — sem ele a API responde 422 PRE_AUTH_SUPPLIER_NAME_REQUIRED. Para fornecedor já cadastrado, é ignorado.

2–255 caracteres
contactName supplier. string opcional

Nome da pessoa de contato. Obrigatório junto com supplier.name quando o CNPJ é novo.

2–255 caracteres
phone supplier. string opcional

Telefone do contato.

até 20 caracteres
invoice object obrigatório

Nota fiscal que será antecipada.
amount invoice. number obrigatório

Valor bruto da nota, em reais. Aceita número ou string numérica ("18400.50").

mín. R$ 500,00máx. R$ 10.000.000,00
dueDate invoice. string obrigatório

Vencimento da nota. Precisa estar entre 5 e 180 dias corridos a partir de hoje (horário de São Paulo) e dentro do prazo máximo do seu limite de crédito.

AAAA-MM-DD
number invoice. string obrigatório

Número da nota fiscal.

1–50 caracteres
withheldTaxAmount invoice. number opcional

Retenções fiscais da nota, em reais. Não pode passar de amount − 500.

mín. R$ 0,00padrão 0
externalReference string opcional

Identificador livre do seu ERP (pedido, título, parcela). Volta em todas as respostas e em todos os webhooks desta operação.

1–100 caracteres

Enviando o arquivo da nota

Para anexar a nota fiscal, use multipart/form-data: mande supplier e invoice como texto JSON e o arquivo no campo invoiceFile.

PDF ou XML, até 10 MB, nome com até 255 caracteres.
O Content-Type do arquivo precisa ser application/pdf, application/xml ou text/xml — e o conteúdo precisa ser mesmo PDF ou XML.

cURL · multipart

curl -X POST https://app.oneos.com.br/api/integration/v1/pre-authorizations \
  -H "Authorization: Bearer $ONEOS_API_KEY" \
  -H "Idempotency-Key: PED-4581-nf-48211-pdf" \
  -F 'supplier={"cnpj":"11.222.333/0001-81","email":"financeiro@fornecedor.com.br"}' \
  -F 'invoice={"amount":18400,"dueDate":"2026-11-30","number":"48211"}' \
  -F 'externalReference=PED-4581' \
  -F 'invoiceFile=@nota-48211.pdf;type=application/pdf'

Resposta

201 Created com a operação:

id integer obrigatório

Identificador da operação na Oneos. É o {id} da consulta e do cancelamento, e o anticipationId dos webhooks.
status enum obrigatório

Status no momento da resposta. Na criação é sempre IN_PRE_AUTH; no cancelamento, REPROVED; na consulta, o status atual.

IN_PRE_AUTHIN_VERIFICATIONTO_APPROVEIN_ANALYSISTO_PAYTO_BILLTO_RECEIVECONCLUDEDREPROVED
externalReference string | null obrigatório

O identificador que você enviou, ou null.
payer object obrigatório

A tomadora, que paga a nota. Na criação, a matriz dona da chave; na consulta e no cancelamento, a empresa da nota (a matriz ou uma filial).
cnpj payer. string obrigatório

CNPJ da tomadora, só dígitos.
name payer. string obrigatório

Razão social da tomadora.
supplier object obrigatório

O fornecedor da operação.
cnpj supplier. string obrigatório

CNPJ normalizado (só dígitos e letras, em maiúsculas).
name supplier. string | null obrigatório

Nome cadastrado na Oneos, ou null.
invoice object obrigatório

Dados da nota como foram gravados.
amount invoice. number obrigatório

Valor bruto, arredondado em centavos.
dueDate invoice. string obrigatório

Vencimento, AAAA-MM-DD.
number invoice. string | null obrigatório

Número da nota.
withheldTaxAmount invoice. number obrigatório

Retenção gravada (0 quando não enviada).
expiresAt string | null obrigatório

Até quando o fornecedor pode solicitar a antecipação. Depois disso a pré-autorização expira sozinha. Veja expiração.
createdAt string obrigatório

Momento da criação, ISO 8601 em UTC.

Requisição

curl -X POST https://app.oneos.com.br/api/integration/v1/pre-authorizations \
  -H "Authorization: Bearer $ONEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: PED-4581-nf-48211" \
  -d '{
    "supplier": { "cnpj": "11.222.333/0001-81", "email": "financeiro@fornecedor.com.br" },
    "invoice": { "amount": 18400, "dueDate": "2026-11-30", "number": "48211" },
    "externalReference": "PED-4581"
  }'

const response = await fetch('https://app.oneos.com.br/api/integration/v1/pre-authorizations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ONEOS_API_KEY}`,
    'Content-Type': 'application/json',
    // mesma chave em toda retentativa desta nota
    'Idempotency-Key': 'PED-4581-nf-48211',
  },
  body: JSON.stringify({
    supplier: { cnpj: '11.222.333/0001-81', email: 'financeiro@fornecedor.com.br' },
    invoice: { amount: 18400, dueDate: '2026-11-30', number: '48211' },
    externalReference: 'PED-4581',
  }),
})

if (!response.ok) {
  const { errors } = await response.json()
  throw new Error(errors.map((e) => `${e.code}: ${e.message}`).join('; '))
}

const preAuthorization = await response.json()
console.log(preAuthorization.id, preAuthorization.status) // 48213 'IN_PRE_AUTH'

import os
import requests

response = requests.post(
    "https://app.oneos.com.br/api/integration/v1/pre-authorizations",
    headers={
        "Authorization": f"Bearer {os.environ['ONEOS_API_KEY']}",
        # mesma chave em toda retentativa desta nota
        "Idempotency-Key": "PED-4581-nf-48211",
    },
    json={
        "supplier": {"cnpj": "11.222.333/0001-81", "email": "financeiro@fornecedor.com.br"},
        "invoice": {"amount": 18400, "dueDate": "2026-11-30", "number": "48211"},
        "externalReference": "PED-4581",
    },
    timeout=30,
)

if not response.ok:
    errors = response.json()["errors"]
    raise RuntimeError("; ".join(f"{e['code']}: {e['message']}" for e in errors))

pre_authorization = response.json()
print(pre_authorization["id"], pre_authorization["status"])  # 48213 IN_PRE_AUTH

<?php
$ch = curl_init('https://app.oneos.com.br/api/integration/v1/pre-authorizations');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('ONEOS_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: PED-4581-nf-48211',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'supplier' => ['cnpj' => '11.222.333/0001-81', 'email' => 'financeiro@fornecedor.com.br'],
        'invoice' => ['amount' => 18400, 'dueDate' => '2026-11-30', 'number' => '48211'],
        'externalReference' => 'PED-4581',
    ]),
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

if ($status >= 400) {
    $messages = array_map(fn ($e) => "{$e['code']}: {$e['message']}", $body['errors']);
    throw new RuntimeException(implode('; ', $messages));
}

echo $body['id'], ' ', $body['status']; // 48213 IN_PRE_AUTH

201 Created

{
  "id": 48213,
  "status": "IN_PRE_AUTH",
  "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"
}

Erros

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

Status	Código	Quando acontece
400	`VALIDATION_ERROR`	Campo ausente ou fora do formato. Um item por problema.
400	`BAD_REQUEST`	Multipart malformado ou campo de arquivo inesperado.
403	`PRE_AUTH_ONLY_CONSTRUTORA`	A empresa da chave não é uma construtora (matriz).
409	`PRE_AUTH_DUPLICATE_INVOICE`	Já existe operação em andamento para a mesma nota (mesmo número) do mesmo fornecedor na sua empresa ou numa filial. O `id` dela vem em `details[0].anticipationId`. Consulte a operação existente em vez de criar outra.
413	`FILE_TOO_LARGE`	Arquivo acima de 10 MB.
422	`ANTICIPATION_INVALID_DUE_DATE`	Vencimento a menos de 5 dias de hoje.
422	`ANTICIPATION_DUE_DATE_TOO_FAR`	Vencimento a mais de 180 dias de hoje.
422	`CREDIT_ANALYSIS_DUE_DATE_EXCEEDED`	Prazo acima do permitido pelo limite de crédito da sua empresa.
422	`CREDIT_ANALYSIS_INVOICE_AMOUNT_EXCEEDED`	Valor acima do permitido pelo limite de crédito da sua empresa.
422	`PRE_AUTH_SUPPLIER_NAME_REQUIRED`	CNPJ ainda não cadastrado e faltou `supplier.name` ou `supplier.contactName`.
422	`PRE_AUTH_SUPPLIER_SELF`	O fornecedor é a sua própria empresa ou uma filial dela.
422	`PRE_AUTH_SUPPLIER_BLOCKED`	O fornecedor está na lista de bloqueio da sua empresa.
422	`INVALID_FILE_TYPE`	O conteúdo do arquivo não é PDF nem XML.
422	`INVOICE_FILE_TYPE`	O `Content-Type` do arquivo não é PDF/XML.
422	`INVOICE_FILE_NAME_TOO_LONG`	Nome do arquivo acima de 255 caracteres.

Nota duplicada

A Oneos recusa uma segunda operação para a mesma nota: mesmo CNPJ de fornecedor e mesmo invoice.number, na sua empresa ou numa filial, enquanto a primeira não terminou (qualquer status fora de REPROVED e CONCLUDED). Vale para operações criadas por qualquer canal, inclusive a plataforma. Depois que a primeira é cancelada, recusada, expira ou conclui, a nota pode ser pré-autorizada de novo.

409 · nota duplicada

{
  "errors": [
    {
      "code": "PRE_AUTH_DUPLICATE_INVOICE",
      "message": "Já existe uma operação em andamento para a nota 48211 deste fornecedor (antecipação 48213)"
    }
  ],
  "details": [
    {
      "anticipationId": 48213
    }
  ]
}