Crear timbrado

Registra un nuevo timbrado en el sistema. Permite crear timbrados con su configuración completa.

Entorno

URL Base: https://api.guarani.app

Endpoint

POST /timbrados

Ejemplo de solicitud

curl -X POST "https://api.guarani.app/timbrados" \
  -H "Content-Type: application/json" \
  -H "x-api-key: Bearer <access_token>" \
  -d '{
    "numero_timbrado": "17677531",
    "vigencia_inicio": "11/09/2025",
    "vigencia_fin": null,
    "numero_solicitud": "364010005683",
    "solicitud_fecha": "11/09/2025",
    "timbrados_documentos": [
      {
        "tipo_comprobante": 1,
        "punto_expedicion": "001",
        "serie_inicial": "AA",
        "inicio_numero": "0000001",
        "fin_numero": "9999999",
        "establecimiento_id": "ejemplo-uuid-establecimiento-123"
      }
    ],
    "actividades_economicas": [
      {
        "actividad_economica_id": "6b91b3a0-0894-45bc-a130-2b58b8eb8e93",
        "es_principal": true
      }
    ],
    "obligaciones": [
      {
        "obligacion_id": "a4889c8c-1730-47f3-9650-b0ba06ae4f50",
          "fecha_inicio": "11/09/2025"
      }
    ]
  }' | jq

Nota: Asegúrate de reemplazar <access_token> con un token JWT válido proporcionado por el equipo Guarani. Importante:
Es imprescindible incluir un token de acceso válido en el encabezado x-api-key para autenticar y autorizar el uso de este endpoint. Sin este token, la solicitud será rechazada.

Encabezados de la solicitud

Encabezado	Valor	Descripción
`Content-Type`	`application/json`	Indica que los datos se envían en formato JSON.
`x-api-key`	`Bearer <access_token>`	Token de autenticación necesario para acceder al recurso.

Descripción de Campos - Timbrado

Campo	Tipo	Requerido	Tamaño	Descripción
`numero_timbrado`	string	Sí	-	Número del timbrado asignado por la SET.
`vigencia_inicio`	date	Sí	-	Fecha de inicio de vigencia del timbrado (formato `DD/MM/YYYY`).
`vigencia_fin`	date	No	-	Fecha de fin de vigencia del timbrado (formato `DD/MM/YYYY`), puede ser nulo.
`numero_solicitud`	string	Sí	-	Número de la solicitud presentada ante la SET.
`solicitud_fecha`	date	Sí	-	Fecha en que fue realizada la solicitud (formato `DD/MM/YYYY`).
`timbrados_documentos`	array	Sí	-	Lista de documentos habilitados por este timbrado.
`actividades_economicas`	array	Sí	-	Lista de actividades económicas relacionadas al timbrado.
`obligaciones`	array	Sí	-	Obligaciones fiscales asociadas al contribuyente.

`timbrados_documentos` (array de objetos)

Campo	Tipo	Requerido	Tamaño	Descripción
`tipo_comprobante`	number	Sí	-	Tipo de comprobante según codificación oficial.
`punto_expedicion`	string	Sí	3	Número del punto de expedición del documento.
`serie_inicial`	string	Sí	3	Serie asignada al timbrado (ejemplo: `"AA"`).
`inicio_numero`	string	Sí	7	Número inicial de la secuencia de documentos.
`fin_numero`	string	Sí	7	Número final de la secuencia de documentos.
`establecimiento_id`	uuid	Sí	36	Identificador único del establecimiento vinculado al timbrado. (ver `establecimientos`).

`actividades_economicas` (array de objetos)

Campo	Tipo	Requerido	Tamaño	Descripción
`actividad_economica_id`	uuid	Sí	36	Identificador único de la actividad económica relacionada. (ver `actividades económicas`).
`es_principal`	boolean	Sí	-	`true` si la actividad es principal, `false` si es secundaria.

`obligaciones` (array de objetos)

Campo	Tipo	Requerido	Tamaño	Descripción
`obligacion_id`	uuid	Sí	36	Identificador único de la obligación fiscal. (ver `obligaciones`).
`fecha_inicio`	date	Sí	-	Fecha en que inicia la obligación (formato `DD/MM/YYYY`).

Ejemplo de respuesta

{
  "success": true,
  "codigo": "201",
  "message": "Recurso creado con éxito.",
  "data": {
    "id": "f57bdf3a-26d0-4a6e-9222-915dcc5c177e",
      "numero_timbrado": "17677531",
      "vigencia_inicio": "11/09/2025",
      "vigencia_fin": null,
      "numero_solicitud": "364010005683",
      "solicitud_fecha": "11/09/2025",
      "timbrados_documentos": [
        {
          "tipo_comprobante": 1,
          "punto_expedicion": "001",
          "serie_inicial": "AA",
          "inicio_numero": "0000001",
          "fin_numero": "9999999",
          "establecimiento": {
            "id": "ejemplo-uuid-establecimiento-123",
            "nombre": "MATRIZ",
            "numero_establecimiento": "001",
            "direccion": "tu direccion",
            "barrio": "tu barrio",
            "ciudad": {
              "id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341",
              "nombre": "SANTA RITA",
              "codigo_sifen": "3556",
              "distrito_id": "78d49201-91f9-4e6c-aadb-4927f56767c0",
              "distrito": {
                "id": "78d49201-91f9-4e6c-aadb-4927f56767c0",
                "codigo": "209",
                "nombre": "SANTA RITA",
                "departamento": {
                  "id": "750d3163-6a53-45df-b349-e8139d1ff3a9",
                  "codigo": "11",
                  "nombre": "ALTO PARANA"
                }
              }
            }
          }
        }
      ],
      "actividades_economicas": [
        {
          "id": "6b91b3a0-0894-45bc-a130-2b58b8eb8e93",
          "codigo": "C4_47110",
          "nombre": "Comercio al por menor en comercios no especializados con surtido compuesto principalmente por alimentos, bebidas o tabaco",
          "es_principal": true
        }
      ],
      "obligaciones": [
        {
          "id": "a4889c8c-1730-47f3-9650-b0ba06ae4f50",
          "codigo": 41,
          "descripcion": "Aporte obrero al Instituto de Previsión Social (IPS)",
          "fecha_inicio": "11/09/2025"
        }
      ]
    }
  }
}

Descripción de campos de respuesta

Campos principales

Campo	Tipo	Descripción
`id`	uuid	Identificador único del timbrado creado.
`numero_timbrado`	string	Número del timbrado asignado por la SET.
`vigencia_inicio`	string	Fecha de inicio de vigencia (formato DD/MM/YYYY).
`vigencia_fin`	string	Fecha de fin de vigencia (formato DD/MM/YYYY), puede ser null.
`numero_solicitud`	string	Número de la solicitud presentada ante la SET.
`solicitud_fecha`	string	Fecha de la solicitud (formato DD/MM/YYYY).
`timbrados_documentos`	array	Lista de documentos habilitados por este timbrado.
`actividades_economicas`	array	Lista de actividades económicas del timbrado.
`obligaciones`	array	Obligaciones fiscales asociadas.

Campos de timbrados_documentos

Campo	Tipo	Descripción
`tipo_comprobante`	number	Tipo de comprobante según codificación SIFEN.
`punto_expedicion`	string	Número del punto de expedición.
`serie_inicial`	string	Serie asignada al timbrado.
`inicio_numero`	string	Número inicial de la secuencia.
`fin_numero`	string	Número final de la secuencia.
`establecimiento`	objeto	Información del establecimiento asociado.

Campos de establecimiento

Campo	Tipo	Descripción
`id`	uuid	Identificador único del establecimiento.
`nombre`	string	Nombre del establecimiento.
`numero_establecimiento`	string	Número que identifica al establecimiento.
`direccion`	string	Dirección física del establecimiento.
`barrio`	string	Nombre del barrio.
`ciudad`	objeto	Información de la ciudad.

Campos de ciudad

Campo	Tipo	Descripción
`id`	uuid	Identificador único de la ciudad.
`nombre`	string	Nombre de la ciudad.
`codigo_sifen`	string	Código de la ciudad según el catálogo SIFEN.
`distrito_id`	uuid	Identificador del distrito.
`distrito`	objeto	Información del distrito.

Campos de distrito

Campo	Tipo	Descripción
`id`	uuid	Identificador único del distrito.
`codigo`	string	Código del distrito.
`nombre`	string	Nombre del distrito.
`departamento`	objeto	Información del departamento.

Campos de departamento

Campo	Tipo	Descripción
`id`	uuid	Identificador único del departamento.
`codigo`	string	Código del departamento.
`nombre`	string	Nombre del departamento.

Campos de actividades_economicas

Campo	Tipo	Descripción
`id`	uuid	Identificador único de la actividad económica.
`codigo`	string	Código de la actividad según el catálogo SIFEN.
`nombre`	string	Descripción de la actividad económica.
`es_principal`	boolean	Indica si la actividad es principal (`true`) o secundaria (`false`).

Campos de obligaciones

Campo	Tipo	Descripción
`id`	uuid	Identificador único de la obligación.
`codigo`	number	Código de la obligación según el catálogo oficial.
`descripcion`	string	Descripción de la obligación fiscal.
`fecha_inicio`	string	Fecha de inicio de la obligación (formato DD/MM/YYYY).

Recursos adicionales

Para más información sobre posibles errores y cómo manejarlos, consulta errores.