> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firmalo.com.mx/llms.txt
> Use this file to discover all available pages before exploring further.

# Inicio rápido

> Crea tu primer documento con flujo de firmas.

En esta guía creas un documento con un firmante y consultas su estado.

## Antes de empezar

Necesitas una [API key](https://docs.firmalo.com.mx/authentication.md) autorizada para crear y consultar documentos, créditos de documento disponibles en tu organización y un PDF.

```bash theme={null}
export FIRMALO_API_URL="https://<host>"
export FIRMALO_API_KEY="<tu-api-key>"
```

## Crea el documento

La petición es `multipart/form-data` con dos campos: `file`, el PDF, y `payload`, un texto con un JSON.

```bash theme={null}
curl -X POST "$FIRMALO_API_URL/api/v1/integration/documents" \
  -H "X-API-Key: $FIRMALO_API_KEY" \
  -H "Idempotency-Key: erp-contrato-2026-000184" \
  -F "file=@contrato.pdf;type=application/pdf" \
  -F 'payload={
    "creator": { "email": "ana.lopez@cliente.example", "firstName": "Ana", "lastName": "López" },
    "document": { "signatureType": "SIMPLE", "isSequential": true },
    "participants": [
      {
        "role": "SIGNER",
        "firstName": "Luis",
        "lastName": "Martínez",
        "email": "luis.martinez@correo.example",
        "order": 1,
        "signaturePositions": [
          { "page": 1, "xRatio": 0.1, "yRatio": 0.8, "widthRatio": 0.25, "heightRatio": 0.08 }
        ]
      }
    ]
  }'
```

* `Idempotency-Key` es obligatorio: un valor único por documento, como el folio de tu sistema. Con él puedes reintentar sin duplicar; lo explica [Idempotencia](https://docs.firmalo.com.mx/idempotency.md).
* `creator` identifica por correo a quien crea el documento. Si no existe, se le da de alta como usuario provisional.
* `order` indica el turno de cada firmante en un documento secuencial: enteros consecutivos desde `1`.
* `signaturePositions` indica dónde va la firma. Los valores son proporciones de la página, de `0` a `1`.

La respuesta es `201` con el identificador del documento:

```json theme={null}
{
  "success": true,
  "message": "Documento y flujo de firmas creados correctamente",
  "data": {
    "id": "2be3b9d7-4c5d-4e6f-8a9b-0c1d2e3f4a5b",
    "status": "PENDING_SIGNATURE",
    "signatureType": "SIMPLE",
    "fileName": "contrato.pdf",
    "createdAt": "2026-10-26T12:00:00.000Z",
    "creator": { "email": "ana.lopez@cliente.example" },
    "participantsCount": 1,
    "publicUrl": "https://app.firmalo.com/public/documents/2be3b9d7-4c5d-4e6f-8a9b-0c1d2e3f4a5b",
    "participants": [
      {
        "email": "luis.martinez@correo.example",
        "status": "PENDING",
        "signatureType": "SIMPLE",
        "order": 1
      }
    ]
  }
}
```

## Consulta el estado

```bash theme={null}
curl "$FIRMALO_API_URL/api/v1/integration/documents?statuses=SIGNED&limit=25" \
  -H "X-API-Key: $FIRMALO_API_KEY"
```

## Siguientes pasos

* Revisa qué hacer cuando algo falla en [Errores](https://docs.firmalo.com.mx/errors.md).
* Consulta todos los campos y endpoints en la pestaña **Referencia API**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.