API v1

Documentação

Uma requisição HTTP, um arquivo, uma resposta em JSON. Base: https://ayla.curae.med.br/v1

Autenticação

Gere um token no seu painel e envie-o em toda requisição. O token aparece uma única vez na criação — guardamos apenas o hash SHA-256 dele.

Authorization: Bearer ayla_a1b2c3_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Também aceitamos o cabeçalho X-Ayla-Token. Requisições sem HTTPS são recusadas.

POST /v1/read

Envia um pedido médico e recebe os dados estruturados. Corpo em multipart/form-data.

Campo	Tipo	Obrigatório	Descrição
arquivo	file	sim	PDF, JPG, PNG ou WEBP com o pedido médico. Até 12 MB e 8 páginas.

O endpoint /v1/pedidos/ler é um apelido do mesmo recurso, para quem prefere rota em português.

Formato da resposta

Campos ilegíveis ou ausentes voltam como null — a Ayla nunca preenche por dedução.

{
  "sucesso": true,
  "paciente": {
    "nome": "João da Silva",
    "cpf": null,
    "data_nascimento": null,
    "sexo": null
  },
  "pedidos": [
    "Hemograma completo",
    "Glicemia de jejum",
    "TSH ultrassensível"
  ],
  "dados": {
    "medico": "Dr. Carlos Mendes",
    "crm": "123456-SP",
    "data_pedido": "12/05/2025",
    "instituicao": null,
    "observacoes": null
  },
  "meta": {
    "referencia": "7c1f9b0e-1f3a-4a55-9c2e-0f2a1b6d4e88",
    "motor": "Ayla IA",
    "confianca": 0.96,
    "itens": 3,
    "paginas": 1,
    "duracao_ms": 4210,
    "documento_armazenado": false,
    "documento_sha256": "9f2c…",
    "modo": "trial",
    "custo": 0,
    "trial_restante": 2
  }
}

Códigos de erro

HTTP	Código	Quando acontece
401	nao_autorizado	Token ausente, inválido, expirado ou revogado.
402	limite_atingido	Teste grátis encerrado e conta ainda sem liberação comercial.
403	nao_autorizado	Conta suspensa.
415	documento_invalido	Formato de arquivo não aceito.
422	documento_invalido	Arquivo ilegível ou que não é um pedido médico.
429	limite_de_requisicoes	Cadência acima do limite do plano.
502	falha_motor	O motor de leitura respondeu com erro.
503	motor_indisponivel	Motor temporariamente indisponível.

{
  "sucesso": false,
  "erro": {
    "codigo": "documento_invalido",
    "mensagem": "O arquivo enviado não parece ser um pedido médico legível."
  }
}

GET /v1/usage

Consumo do mês corrente, saldo do teste grátis e o preço do próximo pedido dentro do cálculo progressivo.

{
  "sucesso": true,
  "periodo": { "inicio": "2026-08-01", "fim": "2026-08-31" },
  "leituras": { "total": 12840, "faturaveis": 12837, "trial_usado": 3, "trial_restante": 0 },
  "faturamento": { "moeda": "BRL", "total": 2118.81, "preco_proximo_pedido": 0.13, "piso": 0.13 }
}

GET /v1/status devolve a situação da conta e serve como sonda de disponibilidade autenticada.

Limites

• 6 requisições/minuto em contas no teste grátis.
• 30 requisições/minuto em contas liberadas.
• Até 12 MB e 8 páginas por arquivo.
• Até 10 tokens ativos por cliente.

Exemplos

cURL

curl -X POST https://ayla.curae.med.br/v1/read \
  -H "Authorization: Bearer $AYLA_TOKEN" \
  -F "arquivo=@pedido.pdf"

PHP

$ch = curl_init('https://ayla.curae.med.br/v1/read');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer '.getenv('AYLA_TOKEN')],
    CURLOPT_POSTFIELDS => ['arquivo' => new CURLFile('pedido.pdf')],
]);

$pedido = json_decode(curl_exec($ch), true);
print_r($pedido['pedidos']);

Node.js

const dados = new FormData();
dados.append('arquivo', new Blob([await readFile('pedido.pdf')]), 'pedido.pdf');

const resposta = await fetch('https://ayla.curae.med.br/v1/read', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.AYLA_TOKEN}` },
  body: dados,
});

const { pedidos } = await resposta.json();

Python

import os, requests

resposta = requests.post(
    "https://ayla.curae.med.br/v1/read",
    headers={"Authorization": f"Bearer {os.environ['AYLA_TOKEN']}"},
    files={"arquivo": open("pedido.pdf", "rb")},
    timeout=180,
)

print(resposta.json()["pedidos"])

Privacidade na integração

O arquivo enviado é processado em memória e descartado ao fim da requisição — não vai para disco, banco ou cache. Do lado da Ayla ficam apenas metadados da chamada (data, tamanho, tempo, tokens do motor e a impressão digital SHA-256 do arquivo), necessários para auditoria e faturamento. Nenhum campo extraído do pedido médico é persistido: eles existem só na resposta que volta para você.

Detalhes de segurança