Lote

Cria em LOTE (até 200) em /tickets

POST/api/v1/tickets/lote

Cria vários registros numa chamada só. Cada item é independente: item inválido não desfaz o lote. A resposta diz, item por item, o que entrou e por que o resto não entrou: 201 quando tudo entrou, 207 quando foi parcial.

Aceita [{...}] ou {"itens":[...]}. Cada item é independente: item inválido NÃO desfaz o lote. Devolve 201 quando tudo entrou e 207 quando o lote foi parcial, com o motivo de cada falha. A Idempotency-Key vale para a chamada inteira, não por item.

Escopo da chave

Exige chave de leitura e escrita (READ_WRITE) com usuário responsável.

Parâmetros

Nome	Onde	Tipo	Obrigatório	Descrição
`Authorization`	header	string	sim	Bearer seguido da chave. Alternativa: cabeçalho X-API-Key.
`Idempotency-Key`	header	string	não	Chave de idempotência (guardada por 24h, corpo de até 2 MB). Repetir a MESMA chave com o MESMO corpo devolve a resposta original gravada, marcada com o header X-Idempotency-Replay: true — nada é executado de novo. A mesma chave com corpo DIFERENTE recebe 409 (conflito); a mesma chave enquanto a primeira execução ainda roda recebe 409 com Retry-After: 5. Resposta 5xx não congela a chave: a repetição executa de novo.

Corpo da requisição

Os campos de cada demanda são os da criação de demanda da API (titulo obrigatório). Limite: 200.

application/json

[ {…}, {…} ]  ·  { "itens": [ {…}, {…} ] }

Nome	Tipo	Obrigatório	Descrição
`titulo`	string	sim	Título da demanda.
`descricao`	string	não	Descrição.
`prioridade`	string	não	Prioridade da demanda (padrão MEDIA).
`clienteId`	integer	não	id de um cliente da conta.
`contratoId`	integer	não	id de um contrato da conta; tem de ser do mesmo cliente da demanda (outro cliente volta 422).
`tipoId`	integer	não	id de um tipo de demanda da conta.

Campos da resposta

Nome	Tipo	Descrição
`total`	integer	Total de itens.
`criados`	integer	Itens criados.
`falhas`	integer	Itens recusados.
`resultados`	array	Um resultado por item, na ordem enviada.
`resultados[].indice`	integer	Posição do item no lote (começa em 0).
`resultados[].status`	string	criado ou erro.
`resultados[].registro`	object	O registro criado (quando status é criado).
`resultados[].erro`	string	O motivo da recusa (quando status é erro).

Códigos de status

HTTP	Descrição
201	Todos os itens criados
207	Lote parcial — veja resultados[].erro
413	Lote acima de 200 itens

Mensagens de erro

HTTP	Mensagem (campo erro)	Quando acontece
401	`chave de API ausente ou inválida`	Sem cabeçalho de chave, chave revogada ou digitada errada.
401	`chave sem empresa vinculada`	A chave existe mas não está ligada a uma conta. Gere outra em Configurações › API.
403	`conta de demonstração: a API pública está desligada na vitrine`	A chamada veio para a conta de demonstração: lá a API pública fica desligada.
403	`identidade da chave de API irregular`	A conta recusa chaves com identidade irregular (pessoa desligada ou chave sem dono). O corpo traz motivo e comoResolver.
429	`limite de requisições excedido (120/min)`	Passou do limite por minuto da chave. Espere o Retry-After.
403	`esta chave é somente leitura — gere uma chave com escopo de escrita`	Escrita com chave de escopo somente leitura.
409	`a chave não tem usuário responsável; recrie a chave em Configurações → API para que os registros criados tenham autoria`	A chave de escrita não tem usuário responsável: sem autoria, nada é gravado.
400	`Idempotency-Key é obrigatória em escrita desde 2026-12-01 (aviso publicado em 2026-09-01): sem ela, um retry de rede cria o registro duas vezes. Envie um valor único por operação no cabeçalho Idempotency-Key.`	Escrita sem Idempotency-Key depois da data de obrigatoriedade.
409	`Idempotency-Key já usada com um corpo DIFERENTE — gere uma chave nova por operação`	A mesma Idempotency-Key veio com outro corpo.
409	`requisicao com esta Idempotency-Key ainda em processamento — aguarde e repita`	A mesma Idempotency-Key chegou enquanto a primeira chamada ainda rodava. Repita depois do Retry-After.
400	`lote vazio`	O lote veio sem nenhum item.
413	`lote com {n} itens; o teto é 200 por chamada`	O lote passou do teto de itens por chamada.
400	`envie um array de itens: [{...}] ou {"itens":[{...}]}`	O corpo não é um array de itens nem um objeto com itens.
207 · resultados[].erro	`titulo é obrigatório`	Lote de demandas: faltou titulo, ou veio vazio (o item volta com status erro).
207 · resultados[].erro	`clienteId não existe nesta empresa`	Lote de demandas: o clienteId não pertence à conta (o item volta com status erro).
207 · resultados[].erro	`tipoId não existe nesta empresa`	Lote de demandas: o tipoId não pertence à conta (o item volta com status erro).
207 · resultados[].erro	`contratoId não existe nesta empresa`	Lote de demandas: o contratoId não pertence à conta (o item volta com status erro).

Exemplo de chamada

cURL

curl -X POST "https://tenka.app.br/api/v1/tickets/lote" \
  -H "Authorization: Bearer $TENKA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '[
  {
    "titulo": "Erro ao emitir a nota",
    "prioridade": "MEDIA",
    "clienteId": 123,
    "contratoId": 45
  },
  {
    "titulo": "Dúvida sobre o boleto",
    "prioridade": "MEDIA",
    "clienteId": 123,
    "contratoId": 45
  }
]'

JavaScript

const response = await fetch("https://tenka.app.br/api/v1/tickets/lote", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + TENKA_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID()
  },
  body: JSON.stringify([
    {
      "titulo": "Erro ao emitir a nota",
      "prioridade": "MEDIA",
      "clienteId": 123,
      "contratoId": 45
    },
    {
      "titulo": "Dúvida sobre o boleto",
      "prioridade": "MEDIA",
      "clienteId": 123,
      "contratoId": 45
    }
  ])
});
const data = await response.json();
if (!response.ok || data.erro) throw new Error(response.status + " " + data.erro);
console.log(data);

Python

import os
import uuid
import requests

response = requests.post(
    "https://tenka.app.br/api/v1/tickets/lote",
    headers={
        "Authorization": f"Bearer {os.environ['TENKA_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json=[
      {
        "titulo": "Erro ao emitir a nota",
        "prioridade": "MEDIA",
        "clienteId": 123,
        "contratoId": 45
      },
      {
        "titulo": "Dúvida sobre o boleto",
        "prioridade": "MEDIA",
        "clienteId": 123,
        "contratoId": 45
      }
    ],
    timeout=30,
)
data = response.json()
if not response.ok or "erro" in data:
    raise RuntimeError(f"{response.status_code} {data.get('erro')}")
print(data)

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder(URI.create("https://tenka.app.br/api/v1/tickets/lote"))
    .header("Authorization", "Bearer " + System.getenv("TENKA_API_KEY"))
    .header("Content-Type", "application/json")
    .header("Idempotency-Key", java.util.UUID.randomUUID().toString())
    .POST(HttpRequest.BodyPublishers.ofString("""
        [
          {
            "titulo": "Erro ao emitir a nota",
            "prioridade": "MEDIA",
            "clienteId": 123,
            "contratoId": 45
          },
          {
            "titulo": "Dúvida sobre o boleto",
            "prioridade": "MEDIA",
            "clienteId": 123,
            "contratoId": 45
          }
        ]
        """))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode() + " " + response.body());

using System.Net.Http.Headers;
using System.Text;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("TENKA_API_KEY"));
var request = new HttpRequestMessage(HttpMethod.Post, "https://tenka.app.br/api/v1/tickets/lote");
request.Headers.Add("Idempotency-Key", Guid.NewGuid().ToString());
request.Content = new StringContent(@"[
  {
    ""titulo"": ""Erro ao emitir a nota"",
    ""prioridade"": ""MEDIA"",
    ""clienteId"": 123,
    ""contratoId"": 45
  },
  {
    ""titulo"": ""Dúvida sobre o boleto"",
    ""prioridade"": ""MEDIA"",
    ""clienteId"": 123,
    ""contratoId"": 45
  }
]", Encoding.UTF8, "application/json");
var response = await http.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

PHP

<?php
$ch = curl_init("https://tenka.app.br/api/v1/tickets/lote");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("TENKA_API_KEY"),
        "Content-Type: application/json",
        "Idempotency-Key: " . bin2hex(random_bytes(16)),
    ],
    CURLOPT_POSTFIELDS => '[
  {
    "titulo": "Erro ao emitir a nota",
    "prioridade": "MEDIA",
    "clienteId": 123,
    "contratoId": 45
  },
  {
    "titulo": "Dúvida sobre o boleto",
    "prioridade": "MEDIA",
    "clienteId": 123,
    "contratoId": 45
  }
]',
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$data = json_decode($body, true);
echo $status . " " . $body;

Node (SDK)

// SDK gerado do contrato — baixe em https://tenka.app.br/api/v1/sdk/tenka.js
import { Tenka } from "./tenka.js";

const tenka = new Tenka(process.env.TENKA_API_KEY, "https://tenka.app.br/api/v1");
const data = await tenka.postTicketsLote({}, [
    {
      "titulo": "Erro ao emitir a nota",
      "prioridade": "MEDIA",
      "clienteId": 123,
      "contratoId": 45
    },
    {
      "titulo": "Dúvida sobre o boleto",
      "prioridade": "MEDIA",
      "clienteId": 123,
      "contratoId": 45
    }
  ], crypto.randomUUID());
console.log(data);

Exemplo de resposta

201 · application/json

{
  "total": 2,
  "criados": 2,
  "falhas": 0,
  "resultados": [
    {
      "indice": 0,
      "status": "criado",
      "registro": {
        "id": 123,
        "titulo": "Erro ao emitir a nota"
      }
    },
    {
      "indice": 1,
      "status": "criado",
      "registro": {
        "id": 124,
        "titulo": "Dúvida sobre o boleto"
      }
    }
  ]
}

Gerado do contrato OpenAPI v1.2.0, o mesmo que o openapi.json publica. openapi.json