Integra el cálculo de plazos con una API sencilla.

Inicio rápido

La API de producción está disponible en https://api.toddle.es. Todas las fechas de entrada y salida utilizan el formato ISO YYYY-MM-DD.

curl -i -X POST 'https://api.toddle.es/api/v1/plazos/vencimiento' -H 'Content-Type: application/json' -H 'X-API-Key: TU_API_KEY' -d '{"codigoIne":"41091","fechaInicio":"2026-04-01","diasHabiles":10,"incluirFechaInicio":false}'

Autenticación

Los endpoints de cálculo requieren la cabecera X-API-Key.

X-API-Key: TU_API_KEY
Content-Type: application/json

No se utiliza Authorization: Bearer. Una cabecera ausente o una clave inválida devuelve 401 API_KEY_INVALIDA.

Pruebas de integración sin consumo

Una vez contratado Toddle Plazos puedes utilizar tu API key real contra dos códigos reservados exclusivamente para pruebas. Sus calendarios son sintéticos, no corresponden a ningún municipio real y las llamadas no descuentan cuota mensual ni bonos.

Para comprobar el subnivel territorial puedes consultar primero el municipio:

curl -i -H 'X-API-Key: TU_API_KEY' 'https://api.toddle.es/api/v1/municipios/99002'

Y después ejecutar un cálculo utilizando la entidad local TEST:

curl -i -X POST 'https://api.toddle.es/api/v1/plazos/vencimiento' -H 'Content-Type: application/json' -H 'X-API-Key: TU_API_KEY' -d '{"codigoIne":"99002","entidadLocal":"test-entidad-001","fechaInicio":"2026-05-14","diasHabiles":3,"incluirFechaInicio":false}'

Java 17+

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

var json = """
    {"codigoIne":"99001","fechaInicio":"2026-03-17","diasHabiles":3,"incluirFechaInicio":false}
    """;
var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.toddle.es/api/v1/plazos/vencimiento"))
    .header("Content-Type", "application/json")
    .header("X-API-Key", System.getenv("TODDLE_API_KEY"))
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();
var response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());

JavaScript (Node.js)

const response = await fetch('https://api.toddle.es/api/v1/plazos/vencimiento', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.TODDLE_API_KEY
  },
  body: JSON.stringify({
    codigoIne: '99001',
    fechaInicio: '2026-03-17',
    diasHabiles: 3,
    incluirFechaInicio: false
  })
});
console.log(response.status, await response.json());

PHP

<?php
$ch = curl_init('https://api.toddle.es/api/v1/plazos/vencimiento');
$body = json_encode([
    'codigoIne' => '99001',
    'fechaInicio' => '2026-03-17',
    'diasHabiles' => 3,
    'incluirFechaInicio' => false
]);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-API-Key: ' . getenv('TODDLE_API_KEY')
    ],
    CURLOPT_POSTFIELDS => $body
]);
echo curl_exec($ch);
curl_close($ch);

Python

import os
import requests

response = requests.post(
    'https://api.toddle.es/api/v1/plazos/vencimiento',
    headers={'X-API-Key': os.environ['TODDLE_API_KEY']},
    json={
        'codigoIne': '99001',
        'fechaInicio': '2026-03-17',
        'diasHabiles': 3,
        'incluirFechaInicio': False,
    },
    timeout=15,
)
print(response.status_code)
print(response.json())

Postman

Crea una petición POST a https://api.toddle.es/api/v1/plazos/vencimiento, añade X-API-Key en Headers y selecciona Body → raw → JSON con:

{
  "codigoIne": "99002",
  "entidadLocal": "test-entidad-001",
  "fechaInicio": "2026-05-14",
  "diasHabiles": 3,
  "incluirFechaInicio": false
}

Consultar municipio y entidades locales

Antes de calcular, una integración puede consultar el modelo territorial del municipio y saber si debe indicar una entidad local.

GET /api/v1/municipios/{codigoIne}

curl -i -H 'X-API-Key: TU_API_KEY' 'https://api.toddle.es/api/v1/municipios/28023'

La respuesta devuelve tipoCalendarioLocal, requiereEntidadLocal y la lista de entidadesLocales con sus códigos públicos estables.

{
  "codigoIne": "28023",
  "nombre": "Boalo, El",
  "provincia": "Madrid",
  "comunidadAutonoma": "Comunidad de Madrid",
  "tipoCalendarioLocal": "POR_ENTIDAD_LOCAL",
  "requiereEntidadLocal": true,
  "entidadesLocales": [
    {"codigo":"cerceda","nombre":"Cerceda","tipo":"NUCLEO_POBLACION"},
    {"codigo":"el-boalo","nombre":"El Boalo","tipo":"NUCLEO_POBLACION"},
    {"codigo":"mataelpino","nombre":"Mataelpino","tipo":"NUCLEO_POBLACION"}
  ]
}

Régimen de cómputo

Las operaciones de cálculo aceptan regimenComputo. Si se omite, se aplica ADMINISTRATIVO, que mantiene el comportamiento habitual basado en sábados, domingos y festivos territoriales.

Calcular vencimiento

Suma un número de días hábiles a una fecha inicial utilizando el calendario correspondiente al municipio.

POST /api/v1/plazos/vencimiento

{
  "codigoIne": "41091",
  "entidadLocal": null,
  "fechaInicio": "2026-04-01",
  "diasHabiles": 10,
  "incluirFechaInicio": false
}

La respuesta incluye la fecha de vencimiento, los días naturales recorridos, los días excluidos y la cobertura utilizada para el cálculo.

Contar días hábiles entre dos fechas

Cuenta los días hábiles de un intervalo y permite decidir si se incluyen sus extremos.

POST /api/v1/plazos/contar

curl -i -X POST 'https://api.toddle.es/api/v1/plazos/contar' -H 'Content-Type: application/json' -H 'X-API-Key: TU_API_KEY' -d '{"codigoIne":"41091","fechaDesde":"2026-04-01","fechaHasta":"2026-04-30","incluirDesde":true,"incluirHasta":true}'

Evaluar un día concreto

Indica si una fecha es hábil o inhábil para un municipio y devuelve los motivos utilizados por el motor de cálculo.

GET /api/v1/calendarios/{codigoIne}/{fecha}?entidadLocal={codigoEntidad}&regimenComputo=JUDICIAL_GENERAL

curl -i -H 'X-API-Key: TU_API_KEY' 'https://api.toddle.es/api/v1/calendarios/41091/2026-04-04'

El parámetro entidadLocal se omite en municipios con calendario municipal y se indica cuando el municipio exige o admite una entidad concreta.

La respuesta contiene fecha, habil, motivos y, cuando corresponda, los festivos aplicados a esa consulta concreta.

Respuestas y cobertura

Las respuestas de cálculo pueden incluir estos bloques:

Consumo y cabeceras

Las respuestas correctas 2xx consumen una llamada, salvo las realizadas contra los códigos sintéticos 99001 y 99002, que no descuentan cuota ni bonos. Los errores de validación, entidad local o cobertura tampoco descuentan cuota. En las respuestas se incluyen cabeceras para conocer la disponibilidad:

Primero se consume la cuota incluida en el plan y, cuando se agota, los bonos activos conforme a su vigencia.

Errores HTTP

Los errores utilizan un cuerpo JSON común:

{
  "codigo": "PARAMETROS_INVALIDOS",
  "mensaje": "Descripción del problema",
  "detalles": null
}

Catálogo de códigos INE

Descarga un catálogo administrativo en formato Excel con tres hojas: comunidades y ciudades autónomas, provincias y municipios.

• CCAA: código, nombre y tipo de entidad.
• Provincias: código, nombre y comunidad autónoma.
• Municipios: código INE, nombre oficial, provincia y comunidad autónoma.

Descargar catálogo INE en Excel

Municipios pendientes de cobertura

Consulta y descarga la relación actual de municipios para los que Toddle Plazos todavía no dispone de cobertura local suficiente para garantizar el cálculo.

• Contenido: comunidad autónoma, provincia, código INE, municipio, estado, motivo y año de referencia.
• Uso recomendado: comprobar previamente si una integración necesita tratar una excepción de cobertura.
• Actualización: el fichero se regenera a partir de la información consolidada y validada del servicio.

Descargar municipios pendientes en Excel

Catálogo de entidades locales

Algunos municipios utilizan calendarios diferenciados por núcleo de población, concejo, entidad local menor u otra entidad territorial. En esos casos, las llamadas de cálculo deben identificar la entidad mediante el parámetro público entidadLocal.

• Detección: consulta GET /api/v1/municipios/{codigoIne} para saber si el municipio requiere entidad local.
• Petición: cuando la API devuelva ENTIDAD_LOCAL_REQUERIDA, repite la llamada incluyendo uno de los códigos públicos admitidos.
• Validación: una entidad solo es válida para su municipio y no todos los municipios permiten este parámetro.
• Contenido del catálogo: comunidad, provincia, código INE, municipio, código público entidadLocal, nombre y tipo de entidad.

Descargar entidades locales en Excel

Cobertura de datos

La cobertura publicada se actualiza a partir de los datos consolidados del servicio. Solo se incorporan territorios después de completar su carga y validación.

• Identificación municipal: las consultas utilizan el código INE.
• Fuentes: diarios oficiales, calendarios laborales y publicaciones de las administraciones competentes.
• Trazabilidad: el motor devuelve metadatos de cobertura y observaciones cuando son relevantes.
• Protección del conjunto de datos: se informa de territorios y años cubiertos sin publicar el calendario municipal consolidado.

Consultar cobertura publicada