Batch

Batch create /clientes (up to 200)

POST/api/v1/clientes/lote

Creates several records in one call. Each item is independent: an invalid item does not undo the batch. The response tells, item by item, what went in and why the rest did not: 201 when everything went in, 207 when partial.

Key scope

Requires a read-write key (READ_WRITE) with a responsible user.

Parameters

Name	In	Type	Required	Description
`Authorization`	header	string	yes	Bearer followed by the key. Alternative: X-API-Key header.
`Idempotency-Key`	header	string	no	Idempotency key (kept 24h, body up to 2 MB). Same key + same body returns the stored original response; same key + different body gets 409; same key while the first run is still going gets 409 with Retry-After: 5. A 5xx does not freeze the key.

Request body

Each item has the same body as the single creation: POST /api/v1/clientes. Limit: 200.

application/json

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

Name	Type	Required	Description
`nome`	string	yes	Name.
`email`	string	no	E-mail.
`cpfCnpj`	string	no	Brazilian tax id (CPF or CNPJ), as registered.
`telefone`	string	no	Phone.

Response fields

Name	Type	Description
`total`	integer	Total items.
`criados`	integer	Items created.
`falhas`	integer	Items refused.
`resultados`	array	One result per item, in the order sent.
`resultados[].indice`	integer	Item position in the batch (starts at 0).
`resultados[].status`	string	criado or erro.
`resultados[].registro`	object	The created record (when status is criado).
`resultados[].erro`	string	The refusal reason (when status is erro).

Status codes

HTTP	Description
201	All items created
207	Partial batch — see resultados[].erro
413	Batch above 200 items

Error messages

HTTP	Message (erro field)	When it happens
401	`chave de API ausente ou inválida`	No key header, revoked key or typo.
401	`chave sem empresa vinculada`	The key exists but is not linked to an account. Create another one in Settings › API.
403	`conta de demonstração: a API pública está desligada na vitrine`	The call reached the demo account, where the public API is turned off.
403	`identidade da chave de API irregular`	The account refuses keys with irregular identity (deactivated person or ownerless key). The body brings motivo and comoResolver.
429	`limite de requisições excedido (120/min)`	The key went over its per-minute limit. Wait for Retry-After.
403	`esta chave é somente leitura — gere uma chave com escopo de escrita`	Write with a read-only key.
409	`a chave não tem usuário responsável; recrie a chave em Configurações → API para que os registros criados tenham autoria`	The write key has no responsible user: without authorship nothing is saved.
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.`	Write without Idempotency-Key after the mandatory date.
409	`Idempotency-Key já usada com um corpo DIFERENTE — gere uma chave nova por operação`	The same Idempotency-Key came with another body.
409	`requisicao com esta Idempotency-Key ainda em processamento — aguarde e repita`	The same Idempotency-Key arrived while the first call was still running. Retry after Retry-After.
400	`lote vazio`	The batch has no items.
413	`lote com {n} itens; o teto é 200 por chamada`	The batch exceeds the per-call item ceiling.
400	`envie um array de itens: [{...}] ou {"itens":[{...}]}`	The body is neither an array of items nor an object with itens.
207 · resultados[].erro	`nome é obrigatório`	Customer or lead batch: nome missing or empty (the item comes back with status erro).

Request example

cURL

curl -X POST "https://tenka.app.br/api/v1/clientes/lote" \
  -H "Authorization: Bearer $TENKA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '[
  {
    "nome": "Comercial Aurora Ltda",
    "email": "contato@exemplo.com",
    "cpfCnpj": "12.345.678/0001-00",
    "telefone": "+55 11 99999-0000"
  },
  {
    "nome": "Padaria Estrela",
    "email": "contato@exemplo.com",
    "cpfCnpj": "12.345.678/0001-00",
    "telefone": "+55 11 99999-0000"
  }
]'

JavaScript

const response = await fetch("https://tenka.app.br/api/v1/clientes/lote", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + TENKA_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID()
  },
  body: JSON.stringify([
    {
      "nome": "Comercial Aurora Ltda",
      "email": "contato@exemplo.com",
      "cpfCnpj": "12.345.678/0001-00",
      "telefone": "+55 11 99999-0000"
    },
    {
      "nome": "Padaria Estrela",
      "email": "contato@exemplo.com",
      "cpfCnpj": "12.345.678/0001-00",
      "telefone": "+55 11 99999-0000"
    }
  ])
});
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/clientes/lote",
    headers={
        "Authorization": f"Bearer {os.environ['TENKA_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json=[
      {
        "nome": "Comercial Aurora Ltda",
        "email": "contato@exemplo.com",
        "cpfCnpj": "12.345.678/0001-00",
        "telefone": "+55 11 99999-0000"
      },
      {
        "nome": "Padaria Estrela",
        "email": "contato@exemplo.com",
        "cpfCnpj": "12.345.678/0001-00",
        "telefone": "+55 11 99999-0000"
      }
    ],
    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/clientes/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("""
        [
          {
            "nome": "Comercial Aurora Ltda",
            "email": "contato@exemplo.com",
            "cpfCnpj": "12.345.678/0001-00",
            "telefone": "+55 11 99999-0000"
          },
          {
            "nome": "Padaria Estrela",
            "email": "contato@exemplo.com",
            "cpfCnpj": "12.345.678/0001-00",
            "telefone": "+55 11 99999-0000"
          }
        ]
        """))
    .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/clientes/lote");
request.Headers.Add("Idempotency-Key", Guid.NewGuid().ToString());
request.Content = new StringContent(@"[
  {
    ""nome"": ""Comercial Aurora Ltda"",
    ""email"": ""contato@exemplo.com"",
    ""cpfCnpj"": ""12.345.678/0001-00"",
    ""telefone"": ""+55 11 99999-0000""
  },
  {
    ""nome"": ""Padaria Estrela"",
    ""email"": ""contato@exemplo.com"",
    ""cpfCnpj"": ""12.345.678/0001-00"",
    ""telefone"": ""+55 11 99999-0000""
  }
]", 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/clientes/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 => '[
  {
    "nome": "Comercial Aurora Ltda",
    "email": "contato@exemplo.com",
    "cpfCnpj": "12.345.678/0001-00",
    "telefone": "+55 11 99999-0000"
  },
  {
    "nome": "Padaria Estrela",
    "email": "contato@exemplo.com",
    "cpfCnpj": "12.345.678/0001-00",
    "telefone": "+55 11 99999-0000"
  }
]',
]);
$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 generated from the contract — download at 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.postClientesLote({}, [
    {
      "nome": "Comercial Aurora Ltda",
      "email": "contato@exemplo.com",
      "cpfCnpj": "12.345.678/0001-00",
      "telefone": "+55 11 99999-0000"
    },
    {
      "nome": "Padaria Estrela",
      "email": "contato@exemplo.com",
      "cpfCnpj": "12.345.678/0001-00",
      "telefone": "+55 11 99999-0000"
    }
  ], crypto.randomUUID());
console.log(data);

Response example

201 · application/json

{
  "total": 2,
  "criados": 2,
  "falhas": 0,
  "resultados": [
    {
      "indice": 0,
      "status": "criado",
      "registro": {
        "id": 123,
        "codigo": 1042,
        "nome": "Comercial Aurora Ltda"
      }
    },
    {
      "indice": 1,
      "status": "criado",
      "registro": {
        "id": 124,
        "codigo": 1043,
        "nome": "Padaria Estrela"
      }
    }
  ]
}

Generated from OpenAPI contract v1.2.0, the same one openapi.json publishes. openapi.json